SDK Architecture

Overview

VoIP & IM Mobile SDK 2.0的整体架构如下图所示（图1），

图1. VoIP & IM Mobile SDK 2.0整体架构

上图中，SDK的核心部分是用C/C++编程语言实现的、具备跨平台运行能力的“VoIP & IM SDK Cross-Platform Kernel”（简称SDK内核）。SDK内核主要负责提供以下核心功能：

业务逻辑：消息发送和接收、群组管理、一对一通话、会议和对讲机等通信业务功能的工作流程和状态机；
云端服务访问：推送通知的发送和接收及云端服务接口访问；
音视频媒体引擎：音视频压缩编码、音视频设备管理、语音信号处理（AGC/AEC/PLC/NS）、视频采集和播放、音频采集和播放；
通信协议栈：会话建立和释放、长连接和HTTP协议栈等；
辅助工具：数据压缩、加密、文字编码等；

此外，SDK API接口分为基本API接口（Basic API）和高级API接口（Advanced API）两种形式。其中，基本API接口采用C语言函数封装的形式，向APP提供面向过程的函数调用接口；高级API接口则采用面向对象的封装方式，向APP提供各种通信服务对象功能。（注：高级API接口将在2015年10月发布）

另一方面，在C/C++ API接口的基础上，针对不同手机操作系统平台，SDK分别采用Objective-C和Java语言对接口进行了轻量封装，以减少APP开发者的学习时间和开发成本。

Modules

VoIP & IM Mobile SDK的API接口可划分为以下功能模块：

基本功能模块（消息和管理模块）– APP授权和管理、用户身份验证和查询、即时消息（一对一和群组消息）和群组管理、文件传输和推送通知等基础功能；
通话功能模块–一对一语音/视频通话、语音/视频会议（服务器混音或客户端混音）；
对讲功能模块（Push-to-Talk）–语音实时对讲；

其中，基本功能模块是APP开发者必须使用的，同时也是其它功能模块的通信基础设施；通话功能模块和对讲功能则是可选的，APP可以根据实际需要进行取舍。

基本功能

基本功能模块的基本架构如下图所示（图2），

图2. 基本功能模块架构

上图中，基本功能模块可划分为四个不同的功能层：接口层、服务层、通信层和协议层。其中，接口层主要负责屏蔽中间件内部的实现细节，为APP提供简单易用的即时通信服务；服务层主要提供APP/用户身份管理和控制，以及各种即时通信业务的工作流程控制；通信层主要提供客户端与服务器之间的交互操作通道，以及确保客户端能够及时获取推送通知；协议层主要负责通信协议报文的封装和解析，以及各种控制信令的处理。

有关基本功能模块的API接口的详细说明参见4.1.1节。

通话功能

通话功能模块的核心是通话状态机，它主要负责记录和管理每个通话的当前状态，并根据用户的操作请求做出相应的处理动作。SDK通话状态机按照下列状态转移图实现通话状态的控制（图3）

图3. 通话状态转移图

上图中，“IDLE”指通话的待机状态，即在发起通话之前或结束通话之后SDK均返回此状态；“INITIATE”指通话发起状态，即在主叫用户发起通话之后，且被叫用户尚未接听之前，通话双方均处于此状态；“ANSWER”指通话接听状态，即在被叫用户接听来电之后，通话双方均处于接听状态；“HANGUP”指通话结束状态，且无论通话双方谁先结束通话，双方都将进入此状态。此外，一旦进入HANGUP状态，SDK会自动转移到IDLE状态。

APP在使用通话功能模块时，需要根据通话的当前状态,或SDK的通话状态通知，显示相应的通话界面，以及执行正确的通话控制操作。

通话功能模块的基本架构如下图所示（图4），

图4. 通话功能模块架构

上图中，通话功能模块可划分为三个不同的功能层：接口层、通话控制和信息处理层和传输协议层。其中，接口层主要负责屏蔽中间件内部的实现细节，为APP提供简单易用的音视频通信服务；通话控制和信息处理层主要提供通话的会话建立、维护和释放的工作流程管理，以及音视频流的压缩编解码、数字信号处理、实时语音质量评估和网络自适应等功能；传输协议层主要负责通信协议报文的封装和解析，以及会话控制信令和媒体流的传输功能。

此外，通话功能模块还负责音视频设备的管理，包括：选择设备、控制设备的工作状态，以及音视频流的采集和播放等功能。

有关通话功能模块的API接口的详细说明参见4.1.2节。

对讲功能

语音对讲功能模块以“频道”为基本业务单元，即频道是语音对讲参与者的基本组织单位。语音对讲功能按照以下基本规则来管理和控制参与者的语音：

只有进入同一个频道内的参与者，才可以相互之间进行实时语音对讲，而一旦离开频道则不能使用语音对讲功能；
参与者以竞争方式获取发言权，且仅在获得授权后方可发送语音；
所有进入频道的参与者可在任何时间收听语音；

对讲功能模块的架构如下图所示（图5），

图5. 对讲功能模块架构

上图中，接口层主要负责屏蔽SDK内部的实现细节，为APP提供简单易用的语音实时对讲服务；PTT控制层主要提供频道的创建/销毁、进入/离开、发言权申请/释放，以及可靠的语音传输等功能；传输协议层主要负责提供频道接入和控制协议、可靠传输协议等。

此外，语音对讲功能的核心是PTT（Push-to-Talk）状态机，它主要负责管理和控制频道的发言状态，以及客户端语音流的发送和接收。PTT状态机按照以下状态转移图实现对讲功能的控制（如图6所示）

图6. 语音对讲状态转移图

其中，“IDLE”指待机状态，即参与者在尚未进入频道或已退出频道时处于此状态；“LISTENING”指收听状态，即参与者在进入频道后自动处于此状态，以收听其它参与者的发言；“WAITING”指发言请求的等待状态，即参与者在请求发言之后，但尚未获得频道发言权之前所处的等待状态；“SPEAKING”指发言状态，即参与者此时已获得发言权后，可以向频道中的其它参与者广播语音流。

APP在使用对讲功能模块时，需要根据频道的当前状态或SDK的PTT状态通知，选择正确的对讲控制操作。

有关对讲功能模块的API接口的详细说明参见4.1.3节。

SDK Package规则

VoIP & IM Mobile SDK工具包的按照以下规则对SDK库进行封装：

1) 按照功能模块的划分及相互之间的依赖性，划分为不同的API接口头文件；
2) SDK库按照功能模块的组合，并搭配相应的API接口文件进行SDK库的封装；

基于上述原则，VoIP & IM Mobile SDK库可根据功能组合划分为以下三种SDK版本：基础版、通话版和增强版。为减少SDK的内存占用，以及实现接口的模块化，APP可按照功能需求，灵活地选择相应的SDK库进行链接。具体的VoIP & IM Mobile SDK库版本如下：

基础版：提供SDK基本功能；
通话版：提供SDK基本功能和通话功能（包含一对一和会议）；
增强版：提供SDK基本功能、通话功能和对讲功能；

上述各种SDK库的封装和API接口之间的关系如下表所示（蓝色字体针对Android黑色针对iOS和Windows），

SDK版本	引用关系(Include/Import)	依赖关系(.a/.so)	功能
基础版	freepp_sdk.h/jar	libFreePPSDKBasic.a/so	1）基础功能（初始化和用户管理） 2）即时消息
通话版	freepp_sdk.h/jar freepp_sdk_stream.h/jar	libFreePPSDKStd.a/so 或 libFreePPSDKStdx.a/so	1）基础功能（初始化和用户管理） 2）即时消息 3）一对一音视频通话 4）多方音视频会议
增强版	freepp_sdk.h/jar freepp_sdk_stream.h/jar freepp_sdk_ptt.h/jar	libFreePPSDKPro.a/so 或 libFreePPSDKProx.a/so	1）基础功能（初始化和用户管理） 2）即时消息 3）一对一音视频通话 4）音视频会议 5）语音对讲

注：通话版和增强版可以生成两个库文件，分别对应客户端混音和服务器混音两种解决方案（后面带x的为服务器混音）。开发者在使用SDK时可根据业务需要从两个库文件中二选一即可。

其中，VoIP & IM Mobile SDK 的API接口函数分别包含在三个不同的头文件中：

FreePPSDK：基本功能API，提供初始化和用户管理等必需的基础功能接口，以及消息相关的接口。
FreePPSDKStream：通话功能API，提供音视频通话和会议相关的控制接口。
FreePPSDKPTT：>对讲功能API，提供实时语音对讲的控制接口。

注：上述划分仅限于接口功能的模块化，不涉及SDK内部模块的实现方式，以及SDK库的版本。

SDK API接口

VoIP & IM Mobile SDK提供三种编程语言的API接口：C/C++、Objective-C和Java。其中，C/C++接口是具备跨平台能力的基本接口；Objective-C和Java接口是在C/C++接口的基础上，分别针对iOS和Android系统提供的，更适合APP应用开发者编程的轻量型封装接口，以降低APP开发者的学习时间和开发成本。

此外，如果没有特别说明，SDK中的API接口默认为同步（阻塞式）调用模式，即在SDK执行完APP所请求的操作之后，函数调用才会返回APP继续执行；否则对于异步（非阻塞式）模式的接口，需要特别说明并指出操作结果返回的回调函数。

注：所有带CALLBACK标注的接口均为回调响应接口，APP需在传递给SDK的FreePPSDKDelegate对象类中实现此回调响应函数，同时避免在回调函数中执行耗时较长的任务，以防止阻塞SDK的工作线程。